『Web API: The Good Parts』
https://gyazo.com/a5f7529d2f1c412697a3abb23a56eadc
2014年11月 発行
224ページ
感想rmaruon.icon
「API作るにあたって、ベストプラクティス的なことをあらかじめ把握してから知りたい」という目的で、手にとった
読む目的は満たせた
内容は少し古いが、Web APIの開発をする前に一読したほうがいい内容が載っている、と初学者ながら感じた
内容の重複、無変換、「たり」の誤用、など一部気になる点はあった
この本の内容を踏まえた上で、「実際にどのように作るか?」を掘っていこうと思う
hr.icon
はじめに
1.1 Web APIの重要性
1.1.1 APIでの利用を前提としたサービスの登場
1.1.2 モバイルアプリケーションと API
1.1.3 APIエコノミー
1.2 さまざまな APIのパターン
1.2.1 公開しているウェブサービスのデータや機能の API公開
1.2.2 他のページに貼り付けるウィジェットの公開
1.2.3 モダンなウェブアプリケーションの構築
1.2.4 スマートフォンアプリケーションの開発
1.2.5 ソーシャルゲームの開発
1.2.6 社内システムの連携
1.3 何を APIで公開すべきか
1.3.1 APIを公開するリスクはあるのか
1.3.2 APIを公開することで得られるもの
1.4 Web APIを美しく設計する重要性
1.4.1 設計の美しい Web APIは使いやすい
1.4.2 設計の美しい Web APIは変更しやすい
1.4.3 設計の美しい Web APIは頑強である
1.4.4 設計の美しい Web APIは恥ずかしくない
1.5 Web APIを美しくするには
1.7 対象となる開発者の数と APIの設計思想
1.8 まとめ
2.1 APIとして公開する機能を設計する
2.1.1 モバイルアプリケーション向け APIに必要な機能
2.2 API エンドポイントの考え方
2.2.1 エンドポイントの基本的な設計
2.3.1 GETメソッド
2.3.2 POSTメソッド
2.3.3 PUTメソッド
2.3.4 DELETEメソッド
2.3.5 PATCHメソッド
2.4 APIのエンドポイント設計
2.4.1 リソースにアクセスするためのエンドポイントの設計の注意点
2.4.2 利用する単語に気をつける
2.4.3 スペースやエンコードを必要とする文字を使わない
2.4.4 単語をつなげる必要がある場合はハイフンを利用する
2.5 検索とクエリパラメータの設計
2.5.1 取得数と取得位置のクエリパラメータ
2.5.2 相対位置を利用する問題点
2.5.3 絶対位置でデータを取得する
2.5.4 絞り込みのためのパラメータ
2.5.5 クエリパラメータとパスの使い分け
2.6.1 アクセストークンの有効期限と更新
2.6.2 その他の Grant Type
2.7 ホスト名とエンドポイントの共通部分
2.8 SSKDsとAPIデザイン
2.9.1 REST LEVEL3 APIのメリット
2.9.2 REST LEVEL3 API
2.10 まとめ
3章 レスポンスデータの設計
3.1 データフォーマット
3.1.1 データフォーマットの指定方法
3.2.1 JSONPをサポートする場合の作法
3.2.2 JSONPとエラー処理
3.3 データの内部構造の考え方
3.3.1 レスポンスの内容をユーザーが選べるようにする
3.3.3 データはフラットにすべきか
3.3.4 配列とフォーマット
3.3.5 配列の件数、あるいは続きがあるかをどう返すべきか
3.4 各データのフォーマット
3.4.1 各データの名前
3.4.2 性別のデータをどう表すか
3.4.3 日付のフォーマット
3.5 レスポンスデータの設計
3.6 エラーの表現
3.6.2 エラーの詳細をクライアントに返す
3.6.3 エラー詳細情報には何を入れるべきか
3.6.4 エラーの際に HTMLが返ることを防ぐ
3.6.5 メンテナンスとステータスコード
3.6.6 意図的に不正確な情報を返したい場合
3.7 まとめ
4.1 HTTPの仕様を利用する意義
4.2 ステータスコードを正しく使う
4.2.1 200番台:成功
4.2.2 300番台追加で処理が必要
4.2.3 クライアントのリクエストに問題があった場合
4.2.4 500番台サーバに問題があった場合
4.3.1 Expiration Model(期限切れモデル)
4.3.2 Validation Model(検証モデル)
4.3.3 Heuristic Expiration(発見的期限切れ)
4.3.4 キャッシュをさせたくない場合
4.3.5 Varyでキャッシュの単位を指定する
4.3.6 Cache-Controlヘッダ
4.4.1 メディアタイプを Content-Typeで指定する必要性
4.4.2 x-で始まるメディアタイプ
4.4.3 自分でメディアタイプを定義する場合
4.4.4 JSONや XMLを用いた新しいデータ形式を定義する場合
4.4.5 メディアタイプとセキュリティ
4.4.6 リクエストデータとメディアタイプ
4.5.2 プリフライトリクエスト
4.5.3 CORSとユーザー認証情報
4.6 独自の HTTPヘッダを定義する
4.7 まとめ
5章 設計変更をしやすいWeb APIを作る
5.1 設計変更のしやすさの重要性
5.1.1 外部に公開している APIの場合
5.1.2 モバイルアプリケーション向け APIの場合
5.1.3 ウェブサービス上で使っている APIの場合
5.2 APIをバージョンで管理する
5.2.1 URIのバージョンを埋め込む
5.2.2 バージョン番号をどう付けるか
5.2.3 バージョンをクエリ文字列に入れる
5.2.4 メディアタイプでバージョンを指定する方法
5.2.5 どの方法を採用するべきか
5.3 バージョンを変える際の指針
5.3.1 常に最新版を返すエイリアスは必要か
5.4 APIの提供を終了する
5.4.1 ケーススタディ : Twitterの場合
5.4.2 あらかじめ提供終了時の仕様を盛り込んでおく
5.4.3 利用規約にサポート期限を明記する
5.5 オーケストレーション層
5.6 まとめ
6章 堅牢なWeb.APIを作る
6.1 Web APIを安全にする
6.1.1 どんなセキュリティの問題があるのか
6.2 サーバとクライアントの間での情報の不正入手
6.2.1 HTTPSによる HTTP通信の暗号化
6.2.2 HTTPSを使えば 100%安全か
6.3 ブラウザでアクセスする APIにおける問題
6.4 悪意あるアクセスへの対策を考える
6.4.1 パラメータの改ざん
6.4.2 リクエストの再送信
6.5 セキュリティ関係の HTTPヘッダ
6.5.1 X-Content-Type-Options
6.5.2 X-XSS-Protection
6.5.3 X-Frame-Options
6.5.4 Content-Security-Policy
6.5.5 Strict-Transpor t-Security
6.5.6 Public-Key-Pins
6.5.7 Set-Cookieヘッダとセキュリティ
6.6 大量アクセスへの対策
6.6.1 ユーザーごとのアクセスを制限する
6.6.2 レートリミットの単位
6.6.3 制限値を超えてしまった場合の対応
6.6.4 レートリミットをユーザーに伝える
6.7 まとめ
付録A Web APIを公開する際にできること
付録B Web .APIチェックリスト
索引
コラム目次
自分の情報へのエイリアス
その他のデータフォーマット
JSONPをサポートすべきか?
HTTP時間の形式
強い検証と弱い検証
バージョン番号を日付で表す
認証局が攻撃を受けて偽の証明書を発行してしまうケース
ブラウザからのアクセスを想定しないAPIの場合
実際のAPIの対応状況を見てみる
アクセス制限の緩和
レートリミットの実装
読んだ